Introduction to XML

Introduction

Welcome back! Today's lesson is all about the fundamentals of XPath, XML's query language. You'll see how to move through XML data, searching for a particular element, and then copying or deleting that element.

Good search tools are flexible. They allow you to specify multiple, complex conditions like, "Show me a list of all TV shows after 1975 that include the word Family." And that's what is so cool about XPath—it's a highly flexible search (or query) language. It searches XML documents so you can retrieve and manipulate elements and their content.

So today we're going to explore XPath. You'll see how to use it to find a recipe with a specific title, such as Beef Tips in Wine Sauce. And then, once that recipe is located, you'll learn how to copy and paste it into a listbox—or if the user requests, you'll delete it from the XML document.

Ready? Let's get started!

Going Down the XPath

You might be surprised to know that you already used XPath! The code in the cookbook program's Listbox_Click event that displays a recipe's instructions contains XPath.

Let's examine that code now. I've highlighted the XPath part:

The user clicks the listbox containing recipe titles. That triggers this sub. The code looks through the recipes.xml document (the doc object in our code) until it locates the recipe containing the title the user clicked. Then, the code fetches that recipe's instructions data and displays them in your textbox named txtInstructions. This way, the user can quickly see any recipe's instructions by just clicking it in the list.

What's happening in this code? It starts off by creating an XmlNode object that I named IndividualRecipe (this object will hold a single recipe element).

Remember

Recall that in XML, an element can be called a node. So you could say that XPath navigates through an XML document, searching for one or more nodes. Technically, node can also refer to other items in XML, like attributes and comments. And XPath can search for them too.

Next, in the second code line, the SelectSingleNode command locates a single target recipe from among all the recipes in the doc (XML file). The target recipe is the one whose title the user clicked. You use XPath to specify which recipe you're looking for.

The second line of code locates and then copies the target recipe into our IndividualRecipe object.

IndividualRecipe = doc.SelectSingleNode("descendant::recipe[title='" & lstTitles.SelectedItem & "']")

How does it do this?

The doc.SelectSingleNode command uses an XPath expression. Think of an expression as the question you're asking, your query. Let's say the user clicked European Spaghetti Sauce in the list. In that case, the query is: "Please give me a copy of the recipe titled European Spaghetti Sauce."

Let's break down our XPath expression one item at a time:

"descendant::recipe[title='" & lstTitles.SelectedItem & "']"

• Descendant: This means the same thing here as it means in English—a child, grandchild, great-grandchild, and so on, descending until there are no more descendants left. The doc.SelectSingleNode method starts by default at the root element. Remember that the root element contains all the rest of the elements in the whole document. So all of the elements are the root's descendants. This is just another way of saying, "Search through all the recipes in this XML document." (XPath offers many more search tools than just this descendant command. See this lesson's FAQs.)

• Recipe: This describes which child elements to look at. In other words, "Only look at elements named recipe."

• Title: This tells the search to find the recipe with the title that matches what the user clicked (lstTitles.SelectedItem).

XPath expression components

Understanding Literals

There's one more item in the XPath expression we should examine. How would you describe  lstTitles.SelectedItem? What does it do?

"descendant::recipe[title='" & lstTitles.SelectedItem & "']"

lstTitles.SelectedItem is technically a pair of items ganged together: a control (the lstTitles listbox) and a property of that control (SelectedItem)—the title that the user clicked (causing it to be highlighted, AKA selected).

But informally you can think of lstTitles.SelectedItem as grouped together and behaving like a variable. While the program runs, the user is free to click any title (this makes it the selected item in the list). Properties like size, color, text, margin, SelectedItem, and so on aren't fixed. While the program is running, they can vary—hence their name: variables.

Variables don't have to vary. You're unlikely to keep changing the form's color all the time. But the user is quite likely to click different titles in the list.

User can select any title listed

The opposite of a variable is a literal. Sometimes code contains information that can't vary, such as the date of the moon landing.

You could rewrite the above XPath expression like this, using literal text. Just replace the variable lstTitles.SelectedItem with a specific, literal title such as Beef Tips in Wine Sauce:

   IndividualRecipe = doc.SelectSingleNode("descendant::recipe[title='Beef Tips in Wine Sauce']")

The obvious problem with this approach is that it ties the user's hands. The user could still click any title in the listbox, but your code would ignore that and always just display the instructions for Beef Tips in Wine Sauce. Clearly you can't use literals in situations like this. But can you think of any situation when you would want to use a literal?

Use literals when there's only one possible choice. For example, you wrote the cookbook program so it will always use the same XML file, and that file is always in the same folder on the hard drive:

Dim RecipesFilePath As String = "C:\xml projects\cookbook\recipes.xml"

Using a literal makes sense here. This filepath never varies. But if you later modify the cookbook program to allow the user to choose from several different cookbooks (several different XML documents, in other words), then clearly you couldn't use a literal. The user's choice would vary.

Dealing With Bizarre Punctuation

One more thing about XPath: What's going on with that weird punctuation and the brackets?

 :: and '" and "' and & 

You just have to live with this when you write an XPath expression. This is another of those copy-it-and-forget-it situations.

There was a meeting somewhere, and they decided this is how it's going to be. Two colons separate the relationship (descendant) from the elements to search through (recipe). Brackets enclose the description of the target recipe. Peculiar single/double/double/single quotation marks enclose the variable containing the specific target term.

Think of this punctuation as a kind of template that you have to type your search request into. It's like one of those forms where they give you one inch to write your entire address. Sometimes you just have to deal with the template they give you, whether it makes much sense or not!

Watching Your Code in Slo-Mo

Now that we've picked apart the code in the lstTitles_Click sub, wouldn't it be helpful (not to mention fun) to be able to see this code execute? And when I say see, I mean watch it perform very slowly, like when a football team looks at a replay of a game.

You can actually do this with the VB editor. It's called single-stepping. Every time you press the F11 key, a single line of code executes and then halts.

Single-stepping is a great way to learn how programming works, but it's also a big help in tracking down errors. When debugging, you frequently need to figure out where something went wrong in the code. Which line of programming is bad? Stepping through the program in slow-motion can sometimes help you zero in on the offending code pretty quickly.

Single-stepping looks like the step-stop stroll of a bride coming down the aisle, or the way Greek soldiers march. But for programmers, this is more than just a stylized walk. It can make the difference between rapidly finding a bug versus the frustration of trying to locate an elusive error.

Let's step through the lstTitles_Click sub. You'll be able to see exactly how the VB code carries out your XPath query.

1. Open the cookbook program in VS.
2. Switch to the code window.
3. Locate the lstTitles_Click sub.
4. Find the first line in this sub: Dim IndividualRecipe As XmlNode.
5. Click the gray bar to the left of that line of code. A red dot appears, like a little stop sign. This red dot is called a breakpoint. (If the editor displays an error message saying "A breakpoint could not be inserted at this location," press F5 to run the program, click the Exit button to stop the program, and then try clicking the gray bar again.)

The red stop sign

Why Use Breakpoints?

To see how XPath works, you want to single-step inside the lstTitles_Click event. That's where the XPath code is, so that's where you want the program to stop.

You could put the breakpoint in the Form_Load event (or any other sub), but you would have to press F11 about two dozen times to step through Form_Load. Why do that? Right now, we're only interested in the lstTitles_Click event. So the red dot goes in the listbox's click event. That way, when you press F5, execution stops where the XPath business is going on.

Similarly, if you were debugging, you'd put the red dot wherever in the code you suspected the bug is lurking. You'd halt execution at that location and begin your close slo-mo examination of what's going on there.

(You can also add multiple breakpoints, but I've never found a reason to do so.)

6. Press F5 to run the program. The program now executes at normal speed through the Form_Load event, but it stops in its tracks at the red dot.

   You're now in break mode. VB is still running the program, but it's paused, like when you press the pause button on the DVD remote. To let you know you're in break mode, the editor highlights the current line of code in yellow (the line where the breakpoint is) and also displays Cookbook (Debugging) up in the top-left corner of the code window.

    
   Execution paused on yellow code line

   Now for something really cool . . .

7. Hover your mouse pointer over the IndividualRecipe variable in the breakpoint line. The editor will tell you the contents of this variable at this point in execution! Since you haven't yet executed this line, the contents are currently nothing:  
   Hovering cursor and variable contents

   Notice in the figure that when in code text, the mouse cursor changes from an arrow to an I-beam.

8. Try hovering your cursor over the other words in this line of code. Here's what happens:

• The editor identifies doc as a document, which we already know. But if you click the small black arrow next to doc, you'll open a scrollable list of way more information about doc than you want to know. Since you wrote this XML document, you already understand that it has child nodes, that its root element is <cookbook>, and so on. But this list could come in very handy if you were working with an XML document that someone else wrote!  
  Tons of info about objects
• Nothing happens when you hover over SelectSingleNode, descendant, or recipe, because they're not variables. So there's no content to display.
• But if you hover over lstTitles, you see its contents: "Beef Tips in Wine Sauce." There's also a small black arrow here, and when you click it, it tells you lots about this listbox control—its position, size, and many other behaviors and properties. But for normal VB programming, you can ignore this list.

Taking the Next Step

Now you've seen what's going on in this line before its code executes. How about what happens after the line uses the XPath expression to locate that specific Beef Tips recipe in the doc?

Let's take a look.

1. Press F11. (If the editor displays a message about an automatic step-over, click No.) The editor now executes the current line of code (yellow) and steps down to the next code line where it halts. When it halts, three things happen in the editor:

• The next line of code turns yellow to show where we're now paused in the code.
• The breakpoint line turns back to red.
• The small yellow arrow on the left moves down to point at the current line.

2. Hover your mouse pointer over LastChild in line 54. You'll see that the recipe element's last child is correctly identified as <instructions>. Recall that the recipe element has only two children, so its FirstChild is <title>, and the LastChild is <instructions>. You've hit pay dirt here, because the whole point of using this XPath expression is to locate the instructions to copy them into the txtInstructions textbox.
3. Hover your mouse pointer over InnerText. There they are—the instructions for the Beef Tips recipe!

Beef Tips recipe instructions

Want to see if you did it correctly? Take a look as I walk through the steps:

Click here to download the video transcript